home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Libraries / stdwin / Doc / ABOUT next >
Encoding:
INI File  |  1991-06-07  |  16.4 KB  |  433 lines  |  [TEXT/????]
  1. [Last modified on Wed Apr 17 10:37:36 MET DST 1991 by frank (Chapters 0, 1, 2)]
  2. [     modified on Sat Apr 15 20:19:00 MET DST 1989 by guido]
  3.  
  4.  
  5. 0. Copyright Notice
  6.  
  7. /***********************************************************
  8. Copyright 1988, 1989, 1991 by Stichting Mathematisch Centrum,
  9. Amsterdam, The Netherlands.
  10.  
  11.                         All Rights Reserved
  12.  
  13. Permission to use, copy, modify, and distribute this software and its 
  14. documentation for any purpose and without fee is hereby granted, 
  15. provided that the above copyright notice appear in all copies and that
  16. both that copyright notice and this permission notice appear in 
  17. supporting documentation, and that the names of Stichting Mathematisch
  18. Centrum or CWI not be used in advertising or publicity pertaining to
  19. distribution of the software without specific, written prior permission.
  20.  
  21. STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
  22. THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  23. FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
  24. FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  25. WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  26. ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  27. OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  28.  
  29. ******************************************************************/
  30.  
  31. 1. Target systems
  32.  
  33. STDWIN is aimed at C programs.  It consists of a few header files (of
  34. which only one is visible to the user) and a library.  In most cases
  35. some system-provided libraries must also be used in the linking phase.
  36.  
  37. Currently, full STDWIN is available for the following environments:
  38.  
  39. (Note that in all cases the code is in beta test state; there may be
  40. bugs, functionality may change slightly in the future and new
  41. functionality may be added, but the basic framework isn't going to
  42. change much.)
  43.  
  44. *       X version 11, release 4 (should still work with release 2 and 3)
  45. *       Apple Macintosh, using either THINK C (4.02) or MPW C (2.02)
  46.  
  47. You may volunteer to create a version for your favourite system, or to
  48. port it to your favourite C compiler for the mentioned micro.
  49.  
  50. A subset, emulating most of STDWIN's functionality on an alphanumeric
  51. display (excluding line drawing, but including multiple (non-overlapping)
  52. windows, menus, text editing etc.) is available for:
  53.  
  54. *       Any decent Unix that has termcap (tested with 4.{2,3} BSD)
  55. *       MS-DOS, using the Microsoft C compiler (4.0)
  56.  
  57. Sorry, there are no versions yet for SunTools, SunView, NeWS, X10,
  58. MS-Windows, Presentation Manager, Atari ST or the Amiga.
  59. The code is remarkably portable to different processor types and
  60. various Unix flavors, as long as they are derived from 4.xBSD.
  61.  
  62.  
  63. 2. Getting the full scoop
  64.  
  65. I have written a paper about STDWIN which has been published as a
  66. CWI report (Guido van Rossum: STDWIN -- A Standard Window System
  67. Interface.  Centre for Mathematics and Computer Science, report
  68. CS-R8817.  Amsterdam, 1988).
  69.  
  70. STDWIN was posted to alt.sources around february 1991.
  71. It should be available from sites that archive this newsgroup, but I
  72. have no information on that.  I also post patches to this group.  (I
  73. will post the entire source to comp.sources.misc when I think the
  74. product is a little bit more finished.)
  75.  
  76. STDWIN is available from a number of ftp sites.
  77. The * in file names is the version number, e.g., 0.9.5 (the last digit
  78. is the patch level).
  79.  
  80. Current version number is 0.9.6 .
  81.  
  82. site        hp4nl.nluug.nl (IP address 192.16.202.2)
  83. for whom    users in the Netherlands and the rest of Europe
  84. file        pub/windows/stdwin*.tar.Z
  85.  
  86. site        wuarchive.wustl.edu (IP address 128.252.135.4)
  87. for whom    users in North America
  88. file        pub/stdwin*.tar.Z
  89.         
  90. site        gatekeeper.dec.com (IP address 16.1.0.2)
  91. for whom    users in North America
  92. file        pub/misc/stdwin*.tar.Z
  93.  
  94. Distribution to to non-ftp-users is solely by electronic mail.  Be
  95. prepared to receive up to half a megabyte (in 32K pieces in "shar"
  96. format).  If you're interested, write to guido@cwi.nl.
  97.  
  98.  
  99. 3. Basic functionality
  100.  
  101. STDWIN allows multiple "full-function" windows, roughly in Macintosh
  102. style (title bar, grow box, close box, scroll bars).  The appearance of
  103. windows is determined by the default of the underlying window manager,
  104. and so are other limitations (e.g., overlapping, maximum size, etc.).
  105. Windows are dynamically created and destroyed by the application, never
  106. directly by the user or the window manager.
  107.  
  108. STDWIN uses a coordinate system derived from the display's coordinate
  109. system: (0, 0) is top left, with X pointing right and Y pointing down
  110. (these are actually called h and v).  Pixel size is that of the display.
  111. There are enquiry functions to ask for the display size in pixels and in
  112. millimeters.
  113.  
  114. The application is responsible for redrawing the window contents when it
  115. is exposed.  This is done by associating a "draw procedure" with each
  116. window, which knows how to draw the entire window's contents.  It gets
  117. passed a pointer to the window and the coordinates of the rectangle that
  118. needs to be redrawn, so it can (although it needn't) restrict itself to
  119. that area.  STDWIN guarantees that a window's redraw procedure is only
  120. called while the application is waiting for an input event (most
  121. implementations simply turn exposure events into calls to the draw
  122. procedure).
  123.  
  124. If the application wants to change part of the graphics it is
  125. displaying, this is usually done in a two-phase process: first, STDWIN
  126. is told that a particular area of the screen must be changed; later,
  127. when the application starts waiting for input events again, the draw
  128. procedure is called to update the indicated area (and any other area
  129. that was exposed or damaged in some way).
  130.  
  131. The application defines the width and height of the area it wants to
  132. draw; this needn't bear any relation to the window or screen size.  This
  133. area is called the "document" although you may also think of it as a
  134. virtual window.  The actual window generally displays a sub-area of the
  135. document; the window's scroll bars indicate the position of the window
  136. with respect to the document.  The application always uses the
  137. coordinates of its document; STDWIN performs the translation to window
  138. or screen coordinates are required by the window manager, and ensures
  139. clipping of all output to the window.
  140.  
  141. STDWIN is event-based.  An application is expected to have a main loop
  142. containing a "get event" call followed by a switch on the event type.
  143. There is no event mask; an application can simply ignore events it isn't
  144. interested in.  The most important event types are:
  145.  
  146. ACTIVATE:       A window becomes active (keyboard attached and/or topmost)
  147.  
  148. CHAR:           ASCII character key pressed (except BS, TAB, CR)
  149.  
  150. COMMAND:        special key or function (CLOSE, TAB, RETURN, BS, CANCEL,
  151.                 arrow keys etc.)
  152.  
  153. MOUSE:          MOUSE DOWN, MOUSE MOVE (only while down), MOUSE UP;
  154.                 fields in the event record indicate the h, v position,
  155.                 the number of the button, and the "click number" if the
  156.                 event is potentially part of a multiple-click sequence
  157.  
  158. MENU:           menu id and item number of a menu selection
  159.  
  160. SIZE:           user has resized the window
  161.  
  162. TIMER:          the window's timer went off; each window has one
  163.                 programmable timer which can be set to go off at N/10
  164.                 seconds in the future.  When the timer goes off a TIMER
  165.                 event is returned.
  166.  
  167. Normally, STDWIN draws text in a single font.  The actual font used
  168. depends on the underlying window manager (and can sometimes be
  169. influenced by the application programmer and/or the end user in a
  170. system-dependent manner).  The font may be proportionally spaced, and
  171. there are enquiry functions to find out the dimensions of characters and
  172. strings.  There are also functions to change the font name and point
  173. size dynamically; but these work different in different systems,
  174. especially the allowed font names differ drastically.  This feature is
  175. used with some success in the ditroff previewer that is supplied as a
  176. demo.
  177.  
  178. There are functions to draw text and simple lines, rectangles and
  179. circles, and ways to erase, shade or invert rectangular areas.  There is
  180. no way (yet) to do general bitblt operations, or to influence the pen
  181. shape.
  182.  
  183.  
  184. 4. Higher level functionality
  185.  
  186. STDWIN provides a blinking vertical bar which can be used to indicate
  187. the text insertion point, so the application needn't use TIMER events to
  188. do the blinking.
  189.  
  190. STDWIN provides Macintosh-style menus.  Each window has its own set of
  191. menus, although by default all menus apply to all windows.  A reasonably
  192. number of menus per window is allowed, each with a reasonable number of
  193. (textual) menu items.  Menus can be changed dynamically.  Items can be
  194. enabled or disabled, and a 'tick mark' can be placed in front of an
  195. item.  Each menu item may have a shortcut character, which, when typed
  196. in combination with some system-defined meta key (e.g., ALT or an ESC-
  197. prefix) selects the menu item (if enabled).  Menu selection is done
  198. completely "underwater"; all the application notices are MENU events.
  199.  
  200. STDWIN has a few simple routines to display Mac-style "dialog boxes",
  201. e.g., to show an error message, or to ask a yes/no question or to ask
  202. for a string to be typed.  There is also a predefined function to ask
  203. for a file name, which may allow the user to browse the file system in
  204. some implementations.
  205.  
  206. STDWIN comes with a package built on top of the basic functionality, to
  207. edit arbitrary blocks of text (cf. Macintosh TEXTEDIT).  In the future,
  208. more packages will be provided, e.g., a package to provide a simple file
  209. editor (available now!), a package to display a scrolling list of items,
  210. a package to define a list of arbitrary labeled "buttons", and a package
  211. to simplify the binding of menus to functions somewhat, and a VT100
  212. emulator (available now!).
  213.  
  214.  
  215. 5. Function definitions
  216.  
  217. Here follows a slightly edited listing of the <stdwin.h> header file,
  218. which more or less documents all available functions and data
  219. structures.  Note that the argument lists are given here as ANSI C
  220. prototypes (untested).
  221.  
  222. #define bool int
  223.  
  224. void winit();
  225. void wdone();
  226.  
  227. void wsetdefwinsize(int width, int height);
  228. void wsetdefwinpos(int h, int v);
  229.  
  230. #define MENU struct menu
  231.  
  232. /* The contents of a text attributes struct are disclosed here because
  233.    the interface allows the programmer to declare objects of this type.
  234.    (I'm not so sure anymore that this is the right thing to do!) */
  235.  
  236. struct textattr {
  237.         short font;
  238.         unsigned char size;
  239.         unsigned char style;
  240. };
  241.  
  242. #define TEXTATTR struct textattr
  243.  
  244. #ifndef WINDOW
  245.  
  246. struct window {
  247.         short tag;
  248. };
  249.  
  250. #define WINDOW struct window
  251.  
  252. #endif
  253.  
  254. WINDOW *wopen(char *title, void drawproc();
  255. void wclose(WINDOW *win);
  256. #define wgettag(win) ((win)->tag)
  257. #define wsettag(win, newtag) ((win)->tag= newtag)
  258. void wsetactive(WINDOW *win);
  259. WINDOW *wgetactive();
  260. void wgetwinsize(WINDOW *win, int *width, int *height);
  261. void wsetdocsize(WINDOW *win, int width, int height);
  262. void wsettitle(WINDOW *win, char *title);
  263.  
  264. void wsetorigin(WINDOW *win, int h, int v);
  265. void wshow(WINDOW *win, int left, int top, int right, int bottom);
  266. void wchange(WINDOW *win, int left, int top, int right, int bottom);
  267. void wscroll(WINDOW *win, int left, int top, int right, int bottom,
  268.         int dh, int dv);
  269.  
  270. void wfleep();
  271. void wmessage(char *str);
  272. void wperror(char *name);
  273. bool waskstr(char *prompt, char *buf, int buflen);
  274. int waskync(char *question, int dflt);
  275. bool waskfile(char *prompt, char *buf, int buflen, bool new);
  276.  
  277. void wsetcaret(WINDOW *win, int h, int v);
  278. void wnocaret(WINDOW *win);
  279.  
  280. void wsettimer(WINDOW *win, int deciseconds);
  281.  
  282. MENU *wmenucreate(int id, char *title);
  283. void wmenudelete(MENU *mp);
  284. int wmenuadditem(MENU *mp, char *text, char shortcut);
  285. void wmenusetitem(MENU *mp, int i, char *text);
  286. void wmenusetdeflocal(bool local);
  287. void wmenuattach(WINDOW *win, MENU *mp);
  288. void wmenudetach(WINDOW *win, MENU *mp);
  289.  
  290. /* EVENT STRUCT DEFINITION */
  291.  
  292. struct event {
  293.         int type;
  294.         WINDOW *window;
  295.         union {
  296.         /* case WE_CHAR: */
  297.                 int character;
  298.         /* case WE_COMMAND: */
  299.                 int command;
  300.         /* case WE_MENU: */
  301.                 struct { int id; int item; } m;
  302.         /* case WE_DRAW: */
  303.                 struct { int left, top, right, bottom; } area;
  304.         /* case WE_MOUSE_DOWN, WE_MOUSE_MOVE, WE_MOUSE_UP: */
  305.                 struct {
  306.                         int v;
  307.                         int h;
  308.                         int clicks;
  309.                         int button;
  310.                         int mask;
  311.                 } where;
  312.         } u;
  313. };
  314.  
  315. #define EVENT struct event
  316.  
  317. /* Event types */
  318.  
  319. #define WE_NULL         0       /* (Used internally) */
  320. #define WE_ACTIVATE     1       /* Window became active */
  321. #define WE_CHAR         2       /* Character typed at keyboard */
  322. #define WE_COMMAND      3       /* Special command, function key etc. */
  323. #define WE_MOUSE_DOWN   4       /* Mouse button pressed */
  324. #define WE_MOUSE_MOVE   5       /* Mouse moved with button down */
  325. #define WE_MOUSE_UP     6       /* Mouse button released */
  326. #define WE_MENU         7       /* Menu item selected */
  327. #define WE_SIZE         8       /* Window size changed */
  328. #define WE_MOVE         9       /* (Reserved) */
  329. #define WE_DRAW         10      /* Request to redraw part of window */
  330. #define WE_TIMER        11      /* Window's timer went off */
  331. #define WE_DEACTIVATE   12      /* Window became inactive */
  332.  
  333. /* Command codes for WE_COMMAND.
  334.    Special ways of entering these are usually available,
  335.    such as clicking icons, standard menu items or special keys.
  336.    Some ASCII keys are also passed back as commands since they
  337.    more often than not need special processing. */
  338.  
  339. #define WC_CLOSE        1       /* Should become a separate event! */
  340. /* The following four are arrow keys */
  341. #define WC_LEFT         2
  342. #define WC_RIGHT        3
  343. #define WC_UP           4
  344. #define WC_DOWN         5
  345. /* ASCII keys */
  346. #define WC_CANCEL       6
  347. #define WC_BACKSPACE    7
  348. #define WC_TAB          8
  349. #define WC_RETURN       9
  350.  
  351. void wgetevent(EVENT *ep);
  352. void wungetevent(EVENT *ep);
  353. void wupdate(WINDOW *win);
  354. void wbegindrawing(WINDOW *win);
  355. void wenddrawing(WINDOW *win);
  356. void wflush();
  357.  
  358. void wdrawline(int h1, int v1, int h2, int v2);
  359. void wxorline(int h1, int v1, int h2, int v2);
  360. void wdrawcircle(int h, int v, int radius);
  361. void wdrawelarc(int h, int v, int radh, int radv, int angle1, int angle2);
  362. void wdrawbox(int left, int top, int right, int bottom);
  363. void werase(int left, int top, int right, int bottom);
  364. void wpaint(int left, int top, int right, int bottom);
  365. void winvert(int left, int top, int right, int bottom);
  366. void wshade(int left, int top, int right, int bottom, int percent);
  367.  
  368. int wdrawtext(int h, int v, char *str, int len);
  369. int wdrawchar(int h, int v, char c);
  370. int wlineheight();
  371. int wtextwidth(char *str, int len);
  372. int wcharwidth(char c);
  373. int wtextbreak(char *str, int len, int width);
  374.  
  375. void wgettextattr(TEXTATTR *attr);
  376. void wsettextattr(TEXTATTR *attr);
  377. void wgetwintextattr(WINDOW *win, TEXTATTR *attr);
  378. void wsetwintextattr(WINDOW *win, TEXTATTR *attr);
  379.  
  380. void wsetplain();
  381. void wsethilite();
  382. void wsetinverse();
  383. void wsetitalic();
  384. void wsetbold();
  385. void wsetbolditalic();
  386. void wsetunderline();
  387.  
  388. /* TEXTEDIT PACKAGE DEFINITIONS */
  389.  
  390. #define TEXTEDIT struct _textedit
  391.  
  392. TEXTEDIT *tealloc(WINDOW *win, int left, int top, int width);
  393. TEXTEDIT *tecreate(WINDOW *win,
  394.         int left, int top, int right, int bottom);
  395. void tefree(TEXTEDIT *tp);
  396. void tedestroy(TEXTEDIT *tp);
  397.  
  398. void tedraw(TEXTEDIT *tp);
  399. void tedrawnew(TEXTEDIT *tp, int left, int top, int right, int bottom);
  400. void temove(TEXTEDIT *tp, int left, int top, int width);
  401. void temovenew(TEXTEDIT *tp,
  402.         int left, int top, int right, int bottom);
  403.  
  404. void tesetfocus(TEXTEDIT *tp, int foc1, int foc2);
  405. void tereplace(TEXTEDIT *tp, char *str);
  406. void tesetbuf(TEXTEDIT *tp, char *buf, int buflen);
  407.  
  408. void tearrow(TEXTEDIT *tp, int code);
  409. void tebackspace(TEXTEDIT *tp);
  410. bool teclicknew(TEXTEDIT *tp, int h, int v, bool extend);
  411. bool tedoubleclick(TEXTEDIT *tp, int h, int v);
  412. bool teevent(TEXTEDIT *tp, EVENT *ep);
  413.  
  414. #define teclick(tp, h, v) teclicknew(tp, h, v, FALSE)
  415. #define teclickextend(tp, h, v) teclicknew(tp, h, v, TRUE)
  416.  
  417. char *tegettext(TEXTEDIT *tp);
  418. int tegetlen(TEXTEDIT *tp);
  419. int tegetnlines(TEXTEDIT *tp);
  420. int tegetfoc1(TEXTEDIT *tp);
  421. int tegetfoc2(TEXTEDIT *tp);
  422. int tegetleft(TEXTEDIT *tp);
  423. int tegettop(TEXTEDIT *tp);
  424. int tegetright(TEXTEDIT *tp);
  425. int tegetbottom(TEXTEDIT *tp);
  426.  
  427. /* Text paragraph drawing functions: */
  428.  
  429. int wdrawpar(int h, int v, char *text, int width);
  430.         /* Returns new v coord. */
  431. int wparheight(char *text, int width);
  432.         /* Returns height */
  433.